Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

OggFLAC/stream_decoder.h: stream decoder interface
[OggFLAC/_decoder.h: decoder interfaces]

This module contains the functions which implement the stream decoder. More...

Compounds

struct  OggFLAC__StreamDecoder

Typedefs

typedef FLAC__StreamDecoderReadStatus(* OggFLAC__StreamDecoderReadCallback )(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)
typedef FLAC__StreamDecoderWriteStatus(* OggFLAC__StreamDecoderWriteCallback )(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(* OggFLAC__StreamDecoderMetadataCallback )(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(* OggFLAC__StreamDecoderErrorCallback )(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

Enumerations

enum  OggFLAC__StreamDecoderState {
  OggFLAC__STREAM_DECODER_OK = 0, OggFLAC__STREAM_DECODER_OGG_ERROR, OggFLAC__STREAM_DECODER_READ_ERROR, OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR,
  OggFLAC__STREAM_DECODER_INVALID_CALLBACK, OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED, OggFLAC__STREAM_DECODER_UNINITIALIZED
}

Functions

OggFLAC_API OggFLAC__StreamDecoderOggFLAC__stream_decoder_new ()
OggFLAC_API void OggFLAC__stream_decoder_delete (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_read_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_write_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_error_callback (OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data (OggFLAC__StreamDecoder *decoder, void *value)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_serial_number (OggFLAC__StreamDecoder *decoder, long serial_number)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond (OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application (OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4])
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore (OggFLAC__StreamDecoder *decoder, FLAC__MetadataType type)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application (OggFLAC__StreamDecoder *decoder, const FLAC__byte id[4])
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all (OggFLAC__StreamDecoder *decoder)
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API unsigned OggFLAC__stream_decoder_get_channels (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API unsigned OggFLAC__stream_decoder_get_bits_per_sample (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API unsigned OggFLAC__stream_decoder_get_sample_rate (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API unsigned OggFLAC__stream_decoder_get_blocksize (const OggFLAC__StreamDecoder *decoder)
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init (OggFLAC__StreamDecoder *decoder)
OggFLAC_API void OggFLAC__stream_decoder_finish (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_flush (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_reset (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_single (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata (OggFLAC__StreamDecoder *decoder)
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream (OggFLAC__StreamDecoder *decoder)

Variables

OggFLAC_API const char *const OggFLAC__StreamDecoderStateString []

Detailed Description

This module contains the functions which implement the stream decoder.

The interface here is identical to FLAC's stream decoder, including the callbacks. See the FLAC stream decoder module for full documentation.


Typedef Documentation

typedef FLAC__StreamDecoderReadStatus(* OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data)
 

Signature for the read callback. See OggFLAC__stream_decoder_set_read_callback() and FLAC__StreamDecoderReadCallback for more info.

Parameters:
decoder  The decoder instance calling the callback.
buffer  A pointer to a location for the callee to store data to be decoded.
bytes  A pointer to the size of the buffer.
client_data  The callee's client data set through OggFLAC__stream_decoder_set_client_data().
Return values:
FLAC__StreamDecoderReadStatus  The callee's return status.

typedef FLAC__StreamDecoderWriteStatus(* OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data)
 

Signature for the write callback. See OggFLAC__stream_decoder_set_write_callback() and FLAC__StreamDecoderWriteCallback for more info.

Parameters:
decoder  The decoder instance calling the callback.
frame  The description of the decoded frame.
buffer  An array of pointers to decoded channels of data.
client_data  The callee's client data set through OggFLAC__stream_decoder_set_client_data().
Return values:
FLAC__StreamDecoderWriteStatus  The callee's return status.

typedef void(* OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
 

Signature for the metadata callback. See OggFLAC__stream_decoder_set_metadata_callback() and FLAC__StreamDecoderMetadataCallback for more info.

Parameters:
decoder  The decoder instance calling the callback.
metadata  The decoded metadata block.
client_data  The callee's client data set through OggFLAC__stream_decoder_set_client_data().

typedef void(* OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)
 

Signature for the error callback. See OggFLAC__stream_decoder_set_error_callback() and FLAC__StreamDecoderErrorCallback for more info.

Parameters:
decoder  The decoder instance calling the callback.
status  The error encountered by the decoder.
client_data  The callee's client data set through OggFLAC__stream_decoder_set_client_data().


Enumeration Type Documentation

enum OggFLAC__StreamDecoderState
 

State values for an OggFLAC__StreamDecoder

The decoder's state can be obtained by calling OggFLAC__stream_decoder_get_state().

Enumeration values:
OggFLAC__STREAM_DECODER_OK  The decoder is in the normal OK state.
OggFLAC__STREAM_DECODER_OGG_ERROR  An error occurred in the underlying Ogg layer.
OggFLAC__STREAM_DECODER_READ_ERROR  The read callback returned an error.
OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR  An error occurred in the underlying FLAC stream decoder; check OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
OggFLAC__STREAM_DECODER_INVALID_CALLBACK  The decoder was initialized before setting all the required callbacks.
OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR  Memory allocation failed.
OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED  OggFLAC__stream_decoder_init() was called when the decoder was already initialized, usually because OggFLAC__stream_decoder_finish() was not called.
OggFLAC__STREAM_DECODER_UNINITIALIZED  The decoder is in the uninitialized state.


Function Documentation

OggFLAC_API OggFLAC__StreamDecoder* OggFLAC__stream_decoder_new  
 

Create a new stream decoder instance. The instance is created with default settings; see the individual OggFLAC__stream_decoder_set_*() functions for each setting's default.

Return values:
OggFLAC__StreamDecoder  * NULL if there was an error allocating memory, else the new instance.

OggFLAC_API void OggFLAC__stream_decoder_delete OggFLAC__StreamDecoder   decoder
 

Free a decoder instance. Deletes the object pointed to by decoder.

Parameters:
decoder  A pointer to an existing decoder.
Assertions:
decoder != NULL 

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_read_callback OggFLAC__StreamDecoder   decoder,
OggFLAC__StreamDecoderReadCallback    value
 

Set the read callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback()

Note:
The callback is mandatory and must be set before initialization.
Default Value:
NULL
Parameters:
decoder  A decoder instance to set.
value  See above.
Assertions:
decoder != NULL 
value != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_write_callback OggFLAC__StreamDecoder   decoder,
OggFLAC__StreamDecoderWriteCallback    value
 

Set the write callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()

Note:
The callback is mandatory and must be set before initialization.
Default Value:
NULL
Parameters:
decoder  A decoder instance to set.
value  See above.
Assertions:
decoder != NULL 
value != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_callback OggFLAC__StreamDecoder   decoder,
OggFLAC__StreamDecoderMetadataCallback    value
 

Set the metadata callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()

Note:
The callback is mandatory and must be set before initialization.
Default Value:
NULL
Parameters:
decoder  A decoder instance to set.
value  See above.
Assertions:
decoder != NULL 
value != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_error_callback OggFLAC__StreamDecoder   decoder,
OggFLAC__StreamDecoderErrorCallback    value
 

Set the error callback. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()

Note:
The callback is mandatory and must be set before initialization.
Default Value:
NULL
Parameters:
decoder  A decoder instance to set.
value  See above.
Assertions:
decoder != NULL 
value != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data OggFLAC__StreamDecoder   decoder,
void *    value
 

Set the client data to be passed back to callbacks. This value will be supplied to callbacks in their client_data argument.

Default Value:
NULL
Parameters:
decoder  A decoder instance to set.
value  See above.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_serial_number OggFLAC__StreamDecoder   decoder,
long    serial_number
 

Set the serial number for the Ogg stream. The default behavior is to use the serial number of the first Ogg page. Setting a serial number here will explicitly define which stream is to be decoded.

Default Value:
use serial number of first page
Parameters:
decoder  A decoder instance to set.
serial_number  See above.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond OggFLAC__StreamDecoder   decoder,
FLAC__MetadataType    type
 

Direct the decoder to pass on all metadata blocks of type type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
type  See above.
Assertions:
decoder != NULL 
type is valid
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_application OggFLAC__StreamDecoder   decoder,
const FLAC__byte    id[4]
 

Direct the decoder to pass on all APPLICATION metadata blocks of the given id. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_application()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
id  See above.
Assertions:
decoder != NULL 
id != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_respond_all OggFLAC__StreamDecoder   decoder
 

Direct the decoder to pass on all metadata blocks of any type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_respond_all()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore OggFLAC__StreamDecoder   decoder,
FLAC__MetadataType    type
 

Direct the decoder to filter out all metadata blocks of type type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
type  See above.
Assertions:
decoder != NULL 
type is valid
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_application OggFLAC__StreamDecoder   decoder,
const FLAC__byte    id[4]
 

Direct the decoder to filter out all APPLICATION metadata blocks of the given id. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_application()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
id  See above.
Assertions:
decoder != NULL 
id != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_ignore_all OggFLAC__StreamDecoder   decoder
 

Direct the decoder to filter out all metadata blocks of any type. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_ignore_all()

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
Parameters:
decoder  A decoder instance to set.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if the decoder is already initialized, else true.

OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_get_state const OggFLAC__StreamDecoder   decoder
 

Get the current decoder state.

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
OggFLAC__StreamDecoderState  The current decoder state.

OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_decoder_state const OggFLAC__StreamDecoder   decoder
 

Get the state of the underlying FLAC stream decoder. Useful when the stream decoder state is OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
FLAC__StreamDecoderState  The FLAC stream decoder state.

OggFLAC_API unsigned OggFLAC__stream_decoder_get_channels const OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels()

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
unsigned  See above.

OggFLAC_API FLAC__ChannelAssignment OggFLAC__stream_decoder_get_channel_assignment const OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channel_assignment()

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
OggFLAC__ChannelAssignment  See above.

OggFLAC_API unsigned OggFLAC__stream_decoder_get_bits_per_sample const OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_bits_per_sample()

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
unsigned  See above.

OggFLAC_API unsigned OggFLAC__stream_decoder_get_sample_rate const OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_sample_rate()

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
unsigned  See above.

OggFLAC_API unsigned OggFLAC__stream_decoder_get_blocksize const OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_blocksize()

Parameters:
decoder  A decoder instance to query.
Assertions:
decoder != NULL 
Return values:
unsigned  See above.

OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init OggFLAC__StreamDecoder   decoder
 

Initialize the decoder instance. Should be called after OggFLAC__stream_decoder_new() and OggFLAC__stream_decoder_set_*() but before any of the OggFLAC__stream_decoder_process_*() functions. Will set and return the decoder state, which will be OggFLAC__STREAM_DECODER_OK if initialization succeeded.

Parameters:
decoder  An uninitialized decoder instance.
Assertions:
decoder != NULL 
Return values:
OggFLAC__StreamDecoderState  OggFLAC__STREAM_DECODER_OK if initialization was successful; see OggFLAC__StreamDecoderState for the meanings of other return values.

OggFLAC_API void OggFLAC__stream_decoder_finish OggFLAC__StreamDecoder   decoder
 

Finish the decoding process. Flushes the decoding buffer, releases resources, resets the decoder settings to their defaults, and returns the decoder state to OggFLAC__STREAM_DECODER_UNINITIALIZED.

In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before OggFLAC__stream_decoder_delete() but it is good practice to match every OggFLAC__stream_decoder_init() with an OggFLAC__stream_decoder_finish().

Parameters:
decoder  An uninitialized decoder instance.
Assertions:
decoder != NULL 

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_flush OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush()

Parameters:
decoder  A decoder instance.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  true if successful, else false if a memory allocation error occurs.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_reset OggFLAC__StreamDecoder   decoder
 

This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_reset()

Parameters:
decoder  A decoder instance.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  true if successful, else false if a memory allocation error occurs.

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_single OggFLAC__StreamDecoder   decoder
 

Decode one metadata block or audio frame. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_single()

Parameters:
decoder  An initialized decoder instance in the state OggFLAC__STREAM_DECODER_OK.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if any read or write error occurred (except FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata OggFLAC__StreamDecoder   decoder
 

Decode until the end of the metadata. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_metadata()

Parameters:
decoder  An initialized decoder instance in the state OggFLAC__STREAM_DECODER_OK.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if any read or write error occurred (except OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).

OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream OggFLAC__StreamDecoder   decoder
 

Decode until the end of the stream. This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_process_until_end_of_stream()

Parameters:
decoder  An initialized decoder instance in the state OggFLAC__STREAM_DECODER_OK.
Assertions:
decoder != NULL 
Return values:
FLAC__bool  false if any read or write error occurred (except OggFLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else true; in any case, check the decoder state with OggFLAC__stream_decoder_get_state() to see what went wrong or to check for lost synchronization (a sign of stream corruption).


Variable Documentation

OggFLAC_API const char* const OggFLAC__StreamDecoderStateString[]
 

Maps an OggFLAC__StreamDecoderState to a C string.

Using an OggFLAC__StreamDecoderState as the index to this array will give the string equivalent. The contents should not be modified.


Generated on Sat Jan 25 10:44:58 2003 for FLAC by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002